<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>hetro</title>
    <link rel="stylesheet" type="text/css" href="csound.css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.78.1" />
    <link rel="home" href="index.html" title="The Canonical Csound Reference Manual" />
    <link rel="up" href="UtilitySoundfile.html#UtilityAnalysis" title="Analysis File Generation (ATSA, CVANAL, HETRO, LPANAL, PVANAL)" />
    <link rel="prev" href="cvanal.html" title="cvanal" />
    <link rel="next" href="lpanal.html" title="lpanal" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">hetro</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="cvanal.html">Prev</a> </td>
          <th width="60%" align="center">Analysis File Generation (ATSA, CVANAL, HETRO, LPANAL, PVANAL)</th>
          <td width="20%" align="right"> <a accesskey="n" href="lpanal.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="refentry">
      <a id="hetro"></a>
      <div class="titlepage"></div>
      <div class="refnamediv">
        <h2>
          <span class="refentrytitle">hetro</span>
        </h2>
        <p>hetro — 
      Decomposes an input soundfile into component sinusoids.
      <a id="IndexHetro" class="indexterm"></a>
    </p>
      </div>
      <div class="refsect1">
        <a id="idp222256368"></a>
        <h2>Description</h2>
        <p>
      Hetrodyne filter analysis for the Csound <a class="link" href="adsyn.html" title="adsyn"><em class="citetitle">adsyn</em></a> generator.
    </p>
      </div>
      <div class="refsect1">
        <a id="idp222326144"></a>
        <h2>Syntax</h2>
        <pre class="synopsis"><span class="command"><strong>csound -U hetro</strong></span> [flags] infilename outfilename</pre>
        <pre class="synopsis"><span class="command"><strong>hetro</strong></span> [flags] infilename outfilename</pre>
      </div>
      <div class="refsect1">
        <a id="idp222329472"></a>
        <h2>Initialization</h2>
        <p>
      <span class="emphasis"><em>hetro</em></span> takes an input soundfile, decomposes it into component sinusoids, and outputs a description of the components in the form of breakpoint amplitude and frequency tracks. Analysis is conditioned by the control flags below. A space is optional between flag and value.
    </p>
        <p>
      <span class="emphasis"><em>-s srate</em></span> -- sampling rate of the audio input file. This will over-ride the srate of the soundfile header, which otherwise applies. If neither is present, the default is 10000. Note that for <span class="emphasis"><em>adsyn</em></span> synthesis the srate of the source file and the generating orchestra need not be the same.
    </p>
        <p>
      <span class="emphasis"><em>-c channel</em></span> -- channel number sought. The default is 1.
    </p>
        <p>
      <span class="emphasis"><em>-b begin</em></span> -- beginning time (in seconds) of the audio segment to be analyzed. The default is 0.0
    </p>
        <p>
      <span class="emphasis"><em>-d duration</em></span> -- duration (in seconds) of the audio segment to be analyzed. The default of 0.0 means to the end of the file. Maximum length is 32.766 seconds.
    </p>
        <p>
      <span class="emphasis"><em>-f begfreq</em></span> -- estimated starting frequency of the fundamental, necessary to initialize the filter analysis. The default is 100 (cps).
    </p>
        <p>
      <span class="emphasis"><em>-h partials</em></span> -- number of harmonic partials sought in the audio file. Default is 10, maximum is a function of memory available.
    </p>
        <p>
      <span class="emphasis"><em>-M maxamp</em></span> -- maximum amplitude summed across all concurrent tracks. The default is 32767.
    </p>
        <p>
      <span class="emphasis"><em>-m minamp</em></span> -- amplitude threshold below which a single pair of amplitude/frequency tracks is considered dormant and will not contribute to output summation. Typical values: 128 (48 db down from full scale), 64 (54 db down), 32 (60 db down), 0 (no thresholding). The default threshold is 64 (54 db down).
    </p>
        <p>
      <span class="emphasis"><em>-n brkpts</em></span> -- initial number of analysis
    breakpoints in each amplitude and frequency track, prior to
    thresholding (<span class="emphasis"><em>-m</em></span>) and linear breakpoint
    consolidation. The initial points are spread evenly over the
    duration. The default is 256.
    </p>
        <p>
      <span class="emphasis"><em>-l cutfreq</em></span> -- substitute a 3rd order
    Butterworth low-pass filter with cutoff frequency
    <span class="emphasis"><em>cutfreq</em></span> (in Hz), in place of the default
    averaging comb filter. The default is 0 (don't use).
    </p>
      </div>
      <div class="refsect1">
        <a id="idp222342400"></a>
        <h2>Performance</h2>
        <p>
      As of Csound 4.08, <span class="emphasis"><em>hetro</em></span> can write SDIF
    output files if the output file name ends with
    ".sdif" or ".SDIF". See the <a class="link" href="sdif2ad.html" title="sdif2ad"><em class="citetitle">sdif2ad utility</em></a>
    for more information about the Csound's SDIF support. 
    </p>
      </div>
      <div class="refsect1">
        <a id="idp222345328"></a>
        <h2>Examples</h2>
        <p>

        </p>
        <pre class="programlisting">
<span class="emphasis"><em>hetro</em></span> -s44100 -b.5 -d2.5 -h16 -M24000 audiofile.test adsynfile7</pre>
        <p>


      This will analyze 2.5 seconds of channel 1 of a file
    "audiofile.test", recorded at 44.1 kHz, beginning .5
    seconds from the start, and place the result in a file
    "adsynfile7". We request just the first 16 harmonics of
    the sound, with 256 initial breakpoint values per amplitude or
    frequency track, and a peak summation amplitude of 24000. The
    fundamental is estimated to begin at 100 Hz. Amplitude
    thresholding is at 54 db down.
    </p>
        <p>
      The Butterworth LPF is not enabled.
    </p>
        <div class="refsect2">
          <a id="HetroFileFormat"></a>
          <h3>File Format</h3>
          <p>
        The output file contains time-sequenced amplitude and
      frequency values for each partial of an additive complex audio
      source. The information is in the form of breakpoints (time,
      value, time, value, ....) using 16-bit integers in the range 0 -
      32767. Time is given in milliseconds, and frequency in Hertz
      (cps). The breakpoint data is exclusively non-negative, and the
      values -1 and -2 uniquely signify the start of new amplitude and
      frequency tracks. A track is terminated by the value
      32767. Before being written out, each track is data-reduced by
      amplitude thresholding and linear breakpoint consolidation. 
      </p>
          <p>
        A component partial is defined by two breakpoint sets: an
      amplitude set, and a frequency set. Within a composite file
      these sets may appear in any order (amplitude, frequency,
      amplitude ....; or amplitude, amplitude..., then frequency,
      frequency,...). During <a class="link" href="adsyn.html" title="adsyn"><em class="citetitle">adsyn</em></a> resynthesis
      the sets are automatically paired (amplitude, frequency) from
      the order in which they were found. There should be an equal
      number of each. 
      </p>
          <p>
        A legal <span class="emphasis"><em>adsyn</em></span> control file could have
        following format: 
        </p>
          <div class="informalexample">
            <pre class="programlisting">
-1 time1 value1 ... timeK valueK 32767 ; amplitude breakpoints for partial 1
-2 time1 value1 ... timeL valueL 32767 ; frequency breakpoints for partial 1
-1 time1 value1 ... timeM valueM 32767 ; amplitude breakpoints for partial 2
-2 time1 value1 ... timeN valueN 32767 ; frequency breakpoints for partial 2
-2 time1 value1 ..........
-2 time1 value1 ..........             ; pairable tracks for partials 3 and 4
-1 time1 value1 ..........
-1 time2 value1 ..........</pre>
          </div>
          <p>
      </p>
        </div>
      </div>
      <div class="refsect1">
        <a id="idp222356880"></a>
        <h2>Credits</h2>
        <p>
        </p>
        <table border="0" summary="Simple list" class="simplelist">
          <tr>
            <td>Author: Tom Sullivan</td>
          </tr>
          <tr>
            <td>1992</td>
          </tr>
          <tr>
            <td>Author: John ffitch</td>
          </tr>
          <tr>
            <td>1994</td>
          </tr>
          <tr>
            <td>Author: Richard Dobson</td>
          </tr>
          <tr>
            <td>2000</td>
          </tr>
        </table>
        <p>
        </p>
        <p>
      October 2002. Thanks to Rasmus Ekman, added a note about the SDIF format.
    </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="cvanal.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="UtilitySoundfile.html#UtilityAnalysis">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="lpanal.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">cvanal </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> lpanal</td>
        </tr>
      </table>
    </div>
  </body>
</html>
